<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1987-2017 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation.  A copy of
the license is included in the
section entitled "GNU Free Documentation License".

This manual contains no Invariant Sections.  The Front-Cover Texts are
(a) (see below), and the Back-Cover Texts are (b) (see below).

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development. -->
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>The C Preprocessor: Variadic Macros</title>

<meta name="description" content="The C Preprocessor: Variadic Macros">
<meta name="keywords" content="The C Preprocessor: Variadic Macros">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Macros.html#Macros" rel="up" title="Macros">
<link href="Predefined-Macros.html#Predefined-Macros" rel="next" title="Predefined Macros">
<link href="Concatenation.html#Concatenation" rel="prev" title="Concatenation">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Variadic-Macros"></a>
<div class="header">
<p>
Next: <a href="Predefined-Macros.html#Predefined-Macros" accesskey="n" rel="next">Predefined Macros</a>, Previous: <a href="Concatenation.html#Concatenation" accesskey="p" rel="prev">Concatenation</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Variadic-Macros-1"></a>
<h3 class="section">3.6 Variadic Macros</h3>
<a name="index-variable-number-of-arguments"></a>
<a name="index-macros-with-variable-arguments"></a>
<a name="index-variadic-macros"></a>

<p>A macro can be declared to accept a variable number of arguments much as
a function can.  The syntax for defining the macro is similar to that of
a function.  Here is an example:
</p>
<div class="smallexample">
<pre class="smallexample">#define eprintf(&hellip;) fprintf (stderr, __VA_ARGS__)
</pre></div>

<p>This kind of macro is called <em>variadic</em>.  When the macro is invoked,
all the tokens in its argument list after the last named argument (this
macro has none), including any commas, become the <em>variable
argument</em>.  This sequence of tokens replaces the identifier
<code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code> in the macro body wherever it appears.  Thus, we
have this expansion:
</p>
<div class="smallexample">
<pre class="smallexample">eprintf (&quot;%s:%d: &quot;, input_file, lineno)
     &rarr;  fprintf (stderr, &quot;%s:%d: &quot;, input_file, lineno)
</pre></div>

<p>The variable argument is completely macro-expanded before it is inserted
into the macro expansion, just like an ordinary argument.  You may use
the &lsquo;<samp>#</samp>&rsquo; and &lsquo;<samp>##</samp>&rsquo; operators to stringize the variable argument
or to paste its leading or trailing token with another token.  (But see
below for an important special case for &lsquo;<samp>##</samp>&rsquo;.)
</p>
<p>If your macro is complicated, you may want a more descriptive name for
the variable argument than <code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code>.  CPP permits
this, as an extension.  You may write an argument name immediately
before the &lsquo;<samp>&hellip;</samp>&rsquo;; that name is used for the variable argument.
The <code>eprintf</code> macro above could be written
</p>
<div class="smallexample">
<pre class="smallexample">#define eprintf(args&hellip;) fprintf (stderr, args)
</pre></div>

<p>using this extension.  You cannot use <code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code> and this
extension in the same macro.
</p>
<p>You can have named arguments as well as variable arguments in a variadic
macro.  We could define <code>eprintf</code> like this, instead:
</p>
<div class="smallexample">
<pre class="smallexample">#define eprintf(format, &hellip;) fprintf (stderr, format, __VA_ARGS__)
</pre></div>

<p>This formulation looks more descriptive, but unfortunately it is less
flexible: you must now supply at least one argument after the format
string.  In standard C, you cannot omit the comma separating the named
argument from the variable arguments.  Furthermore, if you leave the
variable argument empty, you will get a syntax error, because
there will be an extra comma after the format string.
</p>
<div class="smallexample">
<pre class="smallexample">eprintf(&quot;success!\n&quot;, );
     &rarr; fprintf(stderr, &quot;success!\n&quot;, );
</pre></div>

<p>GNU CPP has a pair of extensions which deal with this problem.  First,
you are allowed to leave the variable argument out entirely:
</p>
<div class="smallexample">
<pre class="smallexample">eprintf (&quot;success!\n&quot;)
     &rarr; fprintf(stderr, &quot;success!\n&quot;, );
</pre></div>

<p>Second, the &lsquo;<samp>##</samp>&rsquo; token paste operator has a special meaning when
placed between a comma and a variable argument.  If you write
</p>
<div class="smallexample">
<pre class="smallexample">#define eprintf(format, &hellip;) fprintf (stderr, format, ##__VA_ARGS__)
</pre></div>

<p>and the variable argument is left out when the <code>eprintf</code> macro is
used, then the comma before the &lsquo;<samp>##</samp>&rsquo; will be deleted.  This does
<em>not</em> happen if you pass an empty argument, nor does it happen if
the token preceding &lsquo;<samp>##</samp>&rsquo; is anything other than a comma.
</p>
<div class="smallexample">
<pre class="smallexample">eprintf (&quot;success!\n&quot;)
     &rarr; fprintf(stderr, &quot;success!\n&quot;);
</pre></div>

<p>The above explanation is ambiguous about the case where the only macro
parameter is a variable arguments parameter, as it is meaningless to
try to distinguish whether no argument at all is an empty argument or
a missing argument.  
CPP retains the comma when conforming to a specific C
standard.  Otherwise the comma is dropped as an extension to the standard.
</p>
<p>The C standard 
mandates that the only place the identifier <code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code>
can appear is in the replacement list of a variadic macro.  It may not
be used as a macro name, macro argument name, or within a different type
of macro.  It may also be forbidden in open text; the standard is
ambiguous.  We recommend you avoid using it except for its defined
purpose.
</p>
<p>Variadic macros became a standard part of the C language with C99.  
GNU CPP previously supported them
with a named variable argument
(&lsquo;<samp>args&hellip;</samp>&rsquo;, not &lsquo;<samp>&hellip;</samp>&rsquo; and <code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code>), which
is still supported for backward compatibility.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Predefined-Macros.html#Predefined-Macros" accesskey="n" rel="next">Predefined Macros</a>, Previous: <a href="Concatenation.html#Concatenation" accesskey="p" rel="prev">Concatenation</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
